Converts a collection object into a stream format suitable for storage and unflattening.

OSErr FlattenPartialCollection (
    Collection c, 
    CollectionFlattenUPP flattenProc, 
    void *refCon, 
    SInt32 whichAttributes, 
    SInt32 matchingAttributes
);

c

The collection that you want to flatten. The behavior of this function is undefined if you do not provide a reference to a valid collection object.

flattenProc

A pointer to a function to write data.

refCon

A reference constant that you want the Collection Manager to pass to your flatten function each time it calls the flatten function. You can use this parameter as a pointer to a structure containing information your callback function needs to process the blocks of flattened data.

whichAttributes

A mask indicating which attributes you want to test.

matchingAttributes

An SInt32 word containing the attribute values you want to match.

function result

A result code. This function can return any error returned by the callback function.

DISCUSSION

With this function, you can include in the flattened collection only those items whose attributes match a specified pattern.

The FlattenPartialCollection function flattens into a stream of bytes the collection you specify with the c parameter. It includes only the collection items whose attributes specified by the whichAttributes parameter match the values specified by the matchingAttributes parameter.

As this function flattens the collection, it repeatedly calls the callback function you specify using the flattenProc parameter. Each time it calls this function, it provides the callback function with a pointer to a block of memory containing flattened data. It continues to call this function until it has flattened the entire collection. Your callback function can process the flattened data in a number of ways: it could copy the flattened data into a handle-based block of memory, it could write the flattened data to disk, and so on.

When flattening the c collection, this function includes only the collection items whose persistence attribute is set, regardless of the values you provide in the whichAttributes and matchingAttributes parameters.

To create a flattened collection that includes every item in a collection, use the FlattenCollection function.

To unflatten a flattened collection, use the UnflattenCollection function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)